5 Help for developers

The auth-source library lets you control logging output easily.

Variable: auth-source-debug

Set this variable to 'trivia to see lots of output in *Messages*, or set it to a function that behaves like message to do your own logging.

The auth-source library only has a few functions for external use.

Function: auth-source-search &rest spec &key type max host user port secret require create delete &allow-other-keys

This function searches (or modifies) authentication backends according to spec. See the function’s doc-string for details.

Let’s take a look at an example of using auth-source-search from Gnus’s nnimap.el.

(defun nnimap-credentials (address ports)
  (let* ((auth-source-creation-prompts
          '((user  . "IMAP user at %h: ")
            (secret . "IMAP password for %u@%h: ")))
         (found (nth 0 (auth-source-search :max 1
                                           :host address
                                           :port ports
                                           :require '(:user :secret)
                                           :create t))))
    (if found
        (list (plist-get found :user)
              (let ((secret (plist-get found :secret)))
                (if (functionp secret)
                    (funcall secret)
                  secret))
              (plist-get found :save-function))
      nil)))

This call requires the user and password (secret) to be in the results. It also requests that an entry be created if it doesn’t exist already. While the created entry is being assembled, the shown prompts will be used to interact with the user. The caller can also pass data in auth-source-creation-defaults to supply defaults for any of the prompts.

Note that the password needs to be evaluated if it’s a function. It’s wrapped in a function to provide some security.

Later, after a successful login, nnimap.el calls the :save-function like so:

(when (functionp (nth 2 credentials))
   (funcall (nth 2 credentials)))

This will work whether the :save-function was provided or not. :save-function will be provided only when a new entry was created, so this effectively says “after a successful login, save the authentication information we just used, if it was newly created.”

After the first time it’s called, the :save-function will not run again (but it will log something if you have set auth-source-debug to 'trivia). This is so it won’t ask the same question again, which is annoying. This is so it won’t ask the same question again, which is annoying. This is so it won’t ask the same question again, which is annoying.

So the responsibility of the API user that specified :create t is to call the :save-function if it’s provided.

Function: auth-source-delete &rest spec &key delete &allow-other-keys

This function deletes entries matching spec from the authentication backends. It returns the entries that were deleted. The backend may not actually delete the entries.

Function: auth-source-forget spec

This function forgets any cached data that exactly matches spec. It returns t if it forget some data, and nil if no matching data was found.

Function: auth-source-forget+ &rest spec &allow-other-keys

This function forgets any cached data matching spec. It returns the number of items forgotten.